Get All Chat Sessions

Used to retrieve a list of all chat sessions for a specific agent or project. This endpoint supports pagination and filtering to manage large sets of conversation data.

API Endpoint

Property	Value
Request Method	`POST`
Request URL	`https://api.seliseblocks.com/conversation/sessions`

Request

Request Example

curl -X POST 'https://api.seliseblocks.com/conversation/sessions' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "agent_123",
    "project_key": "YOUR_PROJECT_KEY",
    "limit": 50,
    "offset": 0
  }'

Request Headers

Field	Type	Required	Description
accept	string	Yes	Accepted response format. Use `application/json`
Content-Type	application/json	Yes	Data type, must be `application/json`.

Request Body

Request Body Schema

{
  "agent_id": "string",
  "project_key": "string",
  "limit": 100,
  "offset": 0
}

Request Body Parameters

Field	Type	Required	Description
agent_id	string	Yes	The unique identifier of the AI agent/widget.
project_key	string	Yes	The project key for your project.
limit	integer	No	Maximum number of sessions to return per request (default: 100, max: 100).
offset	integer	No	Number of sessions to skip for pagination (default: 0).

tip

When to use this endpoint:

Admin dashboard: Display all conversations for monitoring and analytics
Session management: List and manage active and historical sessions
Analytics: Analyze conversation patterns and user behavior
Support tools: Access conversation history for customer support
Reporting: Generate reports on chat volume and engagement
Session search: Filter and find specific conversations

Pagination best practices:

Start with offset=0 and limit=50 for initial page
Calculate total pages: Math.ceil(total_count / limit)
Increment offset by limit for each subsequent page
Use limit=100 for bulk data exports
Cache results when appropriate to reduce API calls
Display progress indicator for large result sets

Use cases:

Real-time monitoring: Track active conversations
Historical analysis: Review past interactions
Quality assurance: Audit conversation quality
Training data: Extract conversations for model training
Compliance: Maintain records for regulatory requirements
Customer insights: Understand user needs and pain points

Response

Success Response (200 OK)

Returns a paginated list of chat sessions with metadata.

{
  "sessions": [
    {
      "session_id": "session_abc123",
      "agent_id": "agent_123",
      "widget_id": "widget_456",
      "user_id": "user_789",
      "status": "active",
      "created_at": "2026-01-12T08:30:00Z",
      "updated_at": "2026-01-12T09:45:00Z",
      "last_message_at": "2026-01-12T09:45:00Z",
      "message_count": 15,
      "duration_seconds": 4500,
      "user_info": {
        "name": "John Doe",
        "email": "john@example.com",
        "location": "New York, US"
      },
      "metadata": {
        "source": "website",
        "page_url": "https://example.com/support",
        "device": "desktop",
        "browser": "Chrome"
      },
      "tags": ["support", "billing"],
      "rating": 5,
      "feedback": "Great service!",
      "resolved": true
    },
    {
      "session_id": "session_def456",
      "agent_id": "agent_123",
      "widget_id": "widget_456",
      "user_id": "user_012",
      "status": "closed",
      "created_at": "2026-01-11T14:20:00Z",
      "updated_at": "2026-01-11T14:55:00Z",
      "last_message_at": "2026-01-11T14:55:00Z",
      "message_count": 8,
      "duration_seconds": 2100,
      "user_info": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "metadata": {
        "source": "mobile_app"
      },
      "tags": ["product_inquiry"],
      "rating": 4,
      "resolved": true
    }
  ],
  "total_count": 247
}

Response Fields

Field	Type	Description
sessions	array	Array of session objects containing conversation details.
total_count	integer	Total number of sessions matching the criteria (for pagination).

note

Session Object Structure

Each session object in the array is flexible (additionalProp1: {}) and typically contains:

Core Session Information:

session_id: Unique session identifier
agent_id: Associated AI agent/widget ID
widget_id: Widget used for the conversation
user_id: User identifier (if authenticated)
status: Session status (active, idle, closed, abandoned)

Timestamps:

created_at: Session start time (ISO 8601)
updated_at: Last update time
last_message_at: Timestamp of most recent message
closed_at: Session end time (if closed)

Conversation Metrics:

message_count: Total messages exchanged
duration_seconds: Session duration
response_time_avg: Average agent response time
user_messages: Number of user messages
agent_messages: Number of agent responses

User Information:

user_info: User profile data (name, email, phone, etc.)
user_agent: Browser/device information
ip_address: User IP (if tracked)
location: Geographic location

Metadata and Context:

metadata: Custom fields (source, referrer, campaign, etc.)
tags: Conversation categorization
context: Additional contextual information

Quality Metrics:

rating: User satisfaction rating (1-5)
feedback: User feedback text
resolved: Whether issue was resolved
escalated: If conversation was escalated
sentiment: Overall sentiment analysis

Business Data:

lead_score: Lead quality score
conversion: Whether user converted
revenue: Associated revenue value

Error Response (422 Unprocessable Entity)

Returns validation error details when request parameters are invalid.

{
  "detail": [
    {
      "loc": [
        "body",
        "agent_id"
      ],
      "msg": "Agent not found or access denied",
      "type": "value_error.notfound"
    }
  ]
}

Error Response Fields

Field	Type	Description
detail	array	Array of validation error objects.
loc	array	Location of the error in the request (e.g., body field).
msg	string	Human-readable error message.
type	string	Error type identifier.

Common Error Scenarios

Error Type	Description	Resolution
Agent Not Found	The specified agent_id doesn't exist	Verify agent_id is correct and agent exists
Invalid Project Key	Project key is incorrect or expired	Check project_key credentials
Access Denied	Insufficient permissions to view sessions	Verify API credentials and permissions
Invalid Pagination	Limit or offset values out of range	Ensure limit ≤ 100 and offset ≥ 0
Missing Required Field	agent_id or project_key not provided	Include all required fields in request body

Error Codes

Status Code	Description	Response Type
200	OK - Sessions retrieved successfully	Success
400	Bad Request - Invalid request format	Bad Request
401	Unauthorized - Authentication required	Unauthorized
403	Forbidden - Access denied to sessions	Forbidden
404	Not Found - Agent or project not found	Not Found
422	Validation Error - Invalid parameters	Unprocessable Entity
500	Internal Server Error - Failed to fetch sessions	Internal Server Error

warning

Important Considerations

Performance: Large result sets may take longer to fetch; use appropriate limits
Rate limiting: Avoid excessive pagination requests; implement caching
Data privacy: Ensure compliance with data protection regulations (GDPR, CCPA)
Sensitive data: Filter or mask PII (Personally Identifiable Information) as needed
Real-time updates: Session list may change between paginated requests
Sorting: Results are typically sorted by most recent first
Filtering: Additional filters may be available (status, date range, tags)
Export limits: For bulk exports, consider using dedicated export endpoints
Pagination state: Track current page and total pages in your UI
Memory usage: Be cautious with very large limit values
Authentication: Sessions may contain sensitive user data; secure API access
Archival: Very old sessions may be archived and require separate retrieval

API Endpoint​

Request​

Request Example​

Request Headers​

Request Body​

Request Body Schema​

Request Body Parameters​

Response​

Success Response (200 OK)​

Response Fields​

Error Response (422 Unprocessable Entity)​

Error Response Fields​

Common Error Scenarios​

Error Codes​